主题
XML 错误码说明 - XMLError
XML 模块多数接口通过 err 输出参数 返回 XMLError 枚举值（整数）；部分写操作接口的 返回值 也为错误码。调用方应始终检查错误码，再使用返回值或句柄。
模块总览见 XML 模块总览。
枚举定义
c
// XML 操作错误码枚举
typedef enum {
XML_SUCCESS = 0, // 操作成功
XML_ERROR_INVALID_HANDLE, // 无效的句柄
XML_ERROR_PARSE_FAILED, // XML 解析失败
XML_ERROR_TYPE_MISMATCH, // 类型不匹配
XML_ERROR_ELEMENT_NOT_FOUND, // 元素不存在
XML_ERROR_ATTRIBUTE_NOT_FOUND, // 属性不存在
XML_ERROR_UNKNOWN // 未知错误
} XMLError;未显式赋值的枚举成员从 0 起依次递增，对应整型值如下：
| 常量 | 值 | 说明 |
|---|---|---|
XML_SUCCESS | 0 | 操作成功 |
XML_ERROR_INVALID_HANDLE | 1 | 无效的句柄 |
XML_ERROR_PARSE_FAILED | 2 | XML 解析失败 |
XML_ERROR_TYPE_MISMATCH | 3 | 类型不匹配 |
XML_ERROR_ELEMENT_NOT_FOUND | 4 | 元素不存在 |
XML_ERROR_ATTRIBUTE_NOT_FOUND | 5 | 属性不存在 |
XML_ERROR_UNKNOWN | 6 | 未知错误 |
各错误码详解
XML_SUCCESS（0）
操作正常完成。此时：
- 带
err输出参数 的接口：err == 0，返回值（句柄、字符串指针、数值等）可按文档说明使用。 - 直接返回
int32_t的写操作（如XmlSetAttribute）：返回0表示成功。
XML_ERROR_INVALID_HANDLE（1）
传入的 文档或元素句柄无效，常见原因：
| 场景 | 示例 |
|---|---|
句柄为 0 | 未初始化、查找失败结果被当作有效句柄 |
| 句柄已释放 | 调用 XmlFree 后仍操作文档或其子元素 |
| 句柄来源错误 | 将元素句柄当作文档句柄传入 XmlGetRootElement 等 |
| 子句柄失效 | 父文档释放后，其下元素句柄均不可用 |
处理建议：确认句柄来自 XmlParse、XmlParseFile、XmlCreateDocument 或遍历/查找接口的成功结果，且在 XmlFree 之前使用。
XML_ERROR_PARSE_FAILED（2）
XmlParse、XmlParseFile 无法将输入解析为合法 XML。
常见原因：标签未闭合、非法字符、文件不存在或读取失败、非 XML 文本。
此时文档句柄为 0，err 为 2。勿对失败句柄调用其他 XML 接口。
XML_ERROR_TYPE_MISMATCH（3）
当前操作与节点 实际类型或结构不符。
| 接口 | 典型触发条件 |
|---|---|
XmlGetAttributeInt / XmlGetAttributeDouble 等 | 属性值无法转换为目标类型 |
XmlAppendChild | 父节点不允许挂载该子节点类型 |
XmlGetRootElement | 传入句柄不是文档句柄 |
| 强类型属性读写 | 属性存在但格式与请求类型不匹配 |
XML_ERROR_ELEMENT_NOT_FOUND（4）
找不到指定 元素。
常见于 XmlFindElement、XmlFindElementByAttribute、XmlQueryElement、XmlGetChildByNameAndIndex、XmlRemoveChild 等。也包括遍历轴上 无对应兄弟/子节点 时（如 XmlGetFirstChild 对叶节点返回失败）。
元素名 区分大小写。
XML_ERROR_ATTRIBUTE_NOT_FOUND（5）
元素上找不到指定 属性名。
常见于 XmlGetAttribute、XmlGetAttributeInt、XmlDeleteAttribute、XmlHasAttribute（配合 err 区分「无属性」与「句柄错误」）等。
XML_ERROR_UNKNOWN（6）
未归类的内部错误。若频繁出现，请检查输入数据、句柄生命周期，并向插件维护方反馈复现步骤。
错误码的传递方式
XML 接口以 err 输出参数 为主，写操作常同时通过 返回值 反映结果：
| 类型 | 代表接口 | 如何判断成功 |
|---|---|---|
err 输出参数 | XmlParse、XmlGetRootElement、XmlFindElement、XmlGetAttribute、XmlToString 等绝大多数接口 | err == 0（XML_SUCCESS） |
| 返回值即错误码 | XmlSetAttribute、XmlSetElementText、XmlAppendChild、XmlRemoveChild、XmlDeleteAttribute 等写操作 | 返回 0 表示成功；非 0 为错误码（同时建议检查 err） |
| 返回值表业务结果 | XmlCompareElements（1 相同 / 0 不同）、XmlValidate（1 有效 / 0 无效）、XmlHasChildren / XmlHasAttribute | 以返回值含义为准；接口级错误（如无效句柄）通过 err 返回 |
无 err 参数 | XmlCreateDocument、XmlFree、XmlGetObjectCount、XmlCleanupAll | 按各接口返回值表判断；失败时无 XMLError 明细 |
err 可传 NULL 表示不关心错误详情，但 不建议 在生产代码中忽略。
示例
解析与查找
cpp
int32_t err = 0;
int64_t doc = ola.XmlParse(xmlStr, &err);
if (doc == 0 || err != 0) {
// err == XML_ERROR_PARSE_FAILED (2) 等
return;
}
int32_t findErr = 0;
int64_t user = ola.XmlFindElement(root, "user", &findErr);
if (findErr == XML_ERROR_ELEMENT_NOT_FOUND) {
// 未找到 <user> 元素
}
ola.XmlFree(doc);读取属性
cpp
int32_t err = 0;
const char* level = ola.XmlGetAttribute(element, "level", &err);
if (err == XML_ERROR_ATTRIBUTE_NOT_FOUND) {
// 属性 level 不存在
} else if (err != 0) {
// 其他错误
}写操作
cpp
int32_t err = 0;
int32_t rc = ola.XmlSetAttribute(element, "id", "1", &err);
if (rc != XML_SUCCESS || err != 0) {
// rc 或 err 非 0
}与返回值的关系
部分接口在失败时返回 哨兵值，须结合 err 判断：
| 接口 | 失败时的返回值 | 须同时检查 |
|---|---|---|
XmlParse / XmlParseFile | 0 | err != 0 |
XmlFindElement 等查找类 | 0 | err != 0（未找到时 err 常为 XML_ERROR_ELEMENT_NOT_FOUND） |
XmlGetAttribute / XmlGetElementText / XmlToString | NULL | err != 0 |
XmlGetAttributeDouble | 0.0 | err != 0 |
XmlGetElementDepth | -1 | err != 0 |
XmlGetFirstChild 等遍历轴 | 0 | err != 0（无子节点/兄弟时可能为 XML_ERROR_ELEMENT_NOT_FOUND） |